JSON Library Objects

The JSON functions are exposed in the Business Entities > Library Types > JSON > JSON Array and JSON Object.

You must be familiar with JSON structures. For example, a is an array as indicated by the square brackets [] and b is a JSON object as indicated by the {} brackets.

JSON Sample Projects

There are two sample projects that you can download here to view how to use the various JSON functions:

JSON Test Project that includes some of the simple examples described in this topic.

JSON Presentation Project that includes several examples describing many of the JSON Array and JSON Object functions including those that use a path.

JSON Array

The syntax below references a business entity called myArray (of type JSON Array).

Generally, enumeration in Real-Time Designer starts with 1 (and NOT with 0), therefore, references to elements in a Real-Time Designer JSON array are indexed from 1. For example, to set number 4 as the first element of the myArray JSON array, use: Set Number of myArray4 by index 1.

Function / Event	Return Value	Description	Syntax
Add Boolean to JSON Array	None	Adds a boolean element to the end of the JSON array.	Add Boolean to JSON Array of myArray <Select Boolean>
Add JSON Array	None	Adds a JSON array as an element to the end of the JSON array.	Add JSON Array of myArray <Select JSON Array>
Add JSON Object	None	Adds a JSON object as an element to the JSON array. The entire JSON object becomes the last element in the array.	Add JSON Object of myArray <Select JSON Object>
Add Number to JSON Array	None	Adds a number element to the end of the JSON array.	Add Number to JSON Array of myArray <Select Number>
Add Text to JSON Array	None	Adds a text element to the end of the JSON array.	Add Text to JSON Array of myArray <Select Text >
Contains JSON Array	Boolean	Checks if the element in the index position is a JSON array.	Contains JSON Array of myArray <Select Index>
Contains JSON Object	Boolean	Checks if the element in the index position is a JSON object.	Contains JSON Object of myArray <Select Index>
Contains Value	Boolean	Checks if the element in the index position is a value. A value can be any one of the primitive types: Text, Number, Decimal, DateTime, List or Boolean.	Contains Value of myArray <Select Index>
Count Entries	Number	Returns the number of entries (elements) in the JSON array.	Count Entries of myArray
Get JSON Array by Index	JSON Array	If the element in the index position is a JSON array, the function returns it, otherwise, it returns an empty JSON array.	Get JSON Array by Index of myArray <Select Index>
Get JSON Object by Index	JSON Object	If the element in the index position is a JSON object, the function returns it, otherwise, it returns an empty JSON object.	Get JSON Object by Index of myArray <Select Index>
Get Value by Index	Text	If the element in the index position is a value, the function returns it. A value can be any one of the primitive types: Text, Number, Decimal, DateTime, List or Boolean.	Get Value by Index of myArray <Select Index>
Is Empty	Boolean	Checks if the JSON array is empty. Returns true if the JSON array is empty, otherwise returns false.	Is Empty of myArray
Load from Text	Boolean	Loads the text from the text variable into the JSON array. If the text is able to be converted into a valid JSON array, returns true and if the text is invalid as a JSON array, returns false. This effectively allows you to validate whether a text string is a valid JSON array. For example, use the myArrayinText to create myArray: Load from Text of myArraymyArrayinText When myArrayinText has the initial value of [{"name": "Tom","is citizen": true,"weight": "30.0009","date of birth": "2004-04-09T00:00:00"},{"name": "John","is citizen": true,"weight": "28.6822","date of birth": "2005-09-14T00:00:00"}], this returns a value of True.	Load JSON Array from JSON String of myArray <Select Text>
Remove by Index	Boolean	Deletes the array element in the index position.	Remove by Index of myArray <Select Index>
Set Boolean by Index	Boolean	Sets (adds or updates) the value of the boolean array element in the index position. For example, to set the second element in myArray to true, use: Set Boolean of myArray true by index 2	Set Boolean of myArray <Select Boolean> by index <Select Index>
Set JSON Array by Index	Boolean	Sets (adds or updates) the value of the JSON array element in the index position.	Set JSON Array of myArray <Select JSON Array> by index <Select Index>
Set JSON Object by Index	Boolean	Sets (adds or updates) the value of the JSON object element in the index position.	Set JSON Object of myArray <Select JSON Object> by index <Select Index>
Set Number by Index	Boolean	Sets (adds or updates) the value of the number array element in the index position. For example, to set number 4 as the first element of the JSON array myArray, use: Set Number of myArray 4 by index 1	Set Number of myArray <Select Number> by index <Select Index>

JSON Object

Arrays inside JSON path-related functions, however, follow standard array conventions, and the index starts from 0. For example, to access the value of the “type” key of the first element of the “phoneNumbers” array, use: “$.phoneNumbers[0].type”

The examples use the following business entity variables that include variables of type JSON Object and JSON Array, as well as primitive types such as Boolean, Number, and Text.

Function / Event	Return Value	Description	Syntax
Contains JSON Array	Boolean	Checks if the JSON object includes the named JSON array. For example, to check if myObject includes an array named a: Assign Contains JSON Array of myObject a into myBoolean Where the JSON object was created as follows: Load from Text of myObject {"a":["test",2,[1,2,3],[{"key1":4},{"key2":5},{"key3":6}]],"b":{"key4":null,"key5":"xxxxx"}} In this case, myBoolean will be True as the JSON object includes the array named a. Arrays are indicated by square brackets [].	Contains JSON Array of myObject <Select Name>
Contains JSON Object	Boolean	Checks if the JSON object includes the named JSON object. For example, to check if myObject includes a JSON object named b: Assign Contains JSON Object of myObject b into myBoolean Where the JSON object was created as follows: Load from Text of myObject {"a":["test",2,[1,2,3],[{"key1":4},{"key2":5},{"key3":6}]],"b":{"key4":null,"key5":"xxxxx"}} In this case, myBoolean will be True as the JSON object includes the JSON object named b. JSON objects are indicated by curly brackets {}.	Contains JSON Object of myObject <Select Name>
Contains Value	Boolean	Checks if the JSON object includes the named value. A value can be any one of the primitive types: Text, Number, Decimal, DateTime, List or Boolean. For example, to check if myObject includes a key named test3: Assign Contains Value of myObject test3 into myBoolean Where the JSON object was created as follows: Load from Text of myObject {"test1":2,"test2":true,"test3":"TextValue"} In this case, myBoolean will be True as the JSON object includes test3. This function checks the key (for example, test3) and not the actual key value (for example, TextValue).	Contains Value of myObject <Select Name>
Convert DataTable to JSON Object	JSON Object	Converts an existing DataTable to a JSON object. This function was added in version 7.2.	Convert DataTable to JSON Object <Select DataTable>
Count Entries	Number	Returns the number of key entries (off the root) in the JSON object. For example, to check how many key entries there are in myObject: Assign Count Entries of myObject into myNumber Where the JSON object was created as follows: Load from Text of myObject {"test1":2,"test2":true,"test3":"TextValue"} This example has three entries: This function counts the key entries off the root. For example, this JSON object has two key entries off the root:	Count Entries of myObject
Get JSON Array by Name	JSON Array	Gets a named JSON array from the JSON object. For example, to get the array named a from myObject and into myArray: Assign Get JSON Array by Name of myObject a into myArray Where the JSON object was created as follows: Load from Text of myObject {"a":["test",2,[1,2,3],[{"key1":4},{"key2":5},{"key3":6}]],"b":{"key4":null,"key5":"xxxxx"}}	Get JSON Array by Name of myObject <Select Path>
Get JSON Array by Path	JSON Array	Gets a JSON array by path from the JSON object. For example: $.kids Array indexes inside JSON paths start from 0. For example, to access the value of the “type” key of the first element of the “phoneNumbers” array, use: “$.phoneNumbers[0].type”	Get JSON Array by Path of myObject <Select Name>
Get JSON Object by Name	JSON Object	Gets a named JSON object from the JSON object. For example, to get the JSON object named b from myObject and into mySmallerObject: Assign Get JSON Object by Name of myObject b into mySmallerObject Where the JSON object was created as follows: Load from Text of myObject {"a":["test",2,[1,2,3],[{"key1":4},{"key2":5},{"key3":6}]],"b":{"key4":null,"key5":"xxxxx"}} The resulting extracted JSON object is:	Get JSON Object by Name of myObject <Select Name>
Get JSON Object by Path	JSON Object	Gets a JSON object by path from the JSON object. Path example: $.kids[0].address.garage Array indexes inside JSON paths start from 0.	Get JSON Object by Path of myObject <Select Path>
Get Value by Name	Text	Gets the value of the named key from the JSON object. For example, to get the value of the key named test3 from myObject: Assign Get Value by Name of myObject test3 into myText Where the JSON object was created as follows: Load from Text of myObject {"test1":2,"test2":true,"test3":"TextValue"} In this case, the function returns TextValue	Get Value by Name of myObject <Select Name>
Get Value by Path	Text	Gets the value of the key, specified by the path, from the JSON object. For example: $.kids[0].name. A value can be any one of the primitive types: Text, Number, Decimal, DateTime, List or Boolean. Array indexes inside JSON paths start from 0.	Get Value by Path of myObject <Select Path>
Is Empty	Boolean	Checks if the JSON object is empty. Returns true if the JSON object is empty, otherwise it returns false. For example, check if myObject isempty: Assign Is Empty of myObject into myBoolean Where the JSON object was created as follows: Load from Text of myObject {} In this case, the function returns true as the JSON object is empty.	Is Empty of myObject
Load from Business Entity	None	Generates a JSON object from a user-defined business entity of any type. For example, load Ann's details from a user-defined business entity into a JSON object. The sample project can be downloaded here. Ann business entity with initial values: SC1: AnneJSON JSON Object: Assign Create Business Entity into Ann Load from Business Entity of SC1: AnneJSON ...	Load from Business Entity of myObject ...
Load from Text	Boolean	Loads the text from the text variable into the JSON object. If the text is able to be converted into a valid JSON object, returns true and if the text is invalid as a JSON object, returns false. This effectively allows you to validate whether a text string is a valid JSON object. For example, use the myObjectinText to create myObject: Load from Text of myObject myObjectinText When myObjectinText has the initial value of {"test1":2,"test2":true,"test3":"TextValue"}, this returns a value of True.	Load from Text of myObject <Select Text>
Remove by Name	Boolean	Removes the named element from the JSON object.	Remove by Name of myObject <Select Name>
Save to Business Entity	List of Text	Generates a user-defined business entity from a JSON object and returns a list of warning messages (invalid types). See the sample project for an example. Download it here.	Save to Business Entity <Business Entity>
Save to Text	Text	Saves the JSON object to text.	Save to Text of myObject
Set Boolean by Name	None	Sets (adds or updates) the named boolean key in the JSON Object to true or false. For example, to set the value of the test3 boolean element in myObject to true: Set Boolean of myObject True by Name test3	Set Boolean of myObject <Select Boolean> by Name <Select Name>
Set JSON Array by Name	None	Sets (adds or updates) the named JSON array inside the JSON object. For example, this creates an array with three values and adds these into the myObject as an array called Cars: Add Text to JSON Array of myArray Ford Add Text to JSON Array of myArray Mazda Add Text to JSON Array of myArray Toyota Set JSON Array of myObject myArray by Name Cars Resulting JSON object:	Set JSON Array of myObject <Select JSON Array> by Name <Select Name>
Set JSON Object by Name	JSON Object	Sets (adds or updates) a named JSON object inside the JSON object. For example, to add the element named a in myObject to the value of the mySmallerObject: Set JSON Object of myObject mySmallerObject by Name a Where the JSON mySmallerObject was created as follows: Load from Text of mySmallerObject {"fruit": "Apple","size": "Large","color": "Red"} Resulting JSON object:	Set JSON Object of myObject <Select JSON Object> by Name <Select Name>
Set Number by Name	None	Sets (adds or updates) the named number element in the JSON object. For example, to set the value of the test1 number element in myObject to 1000: Set Number of myObject 1000 into test1 Where the JSON object was created as follows: Load from Text of myObject {"test1":2,"test2":true,"test3":"TextValue"}	Set Number of myObject <Select Number> by Name <Select Name>
Set Text by Name	Boolean	Sets (adds or updates) the named text element in the JSON object. For example, to set the value of the test3 text element in myObject to Hello World: Set Text of myObject Hello World into test3 Where the JSON object was created as follows: Load from Text of myObject {"test1":2,"test2":true,"test3":"TextValue"} Resulting JSON object:	Set Text of myObject <Select Text> by Name <Select Name>
Set Text by Path	Boolean	Sets (adds or updates) the text element specified by the path in the JSON object. Array indexes inside JSON paths start from 0.	Set Text of myObject <Select Text> by Name <Select Name>

JSON Path

Arrays in JSON path-related functions follow standard array conversions, and the index starts from 0.

For example, $.phoneNumbers[0].type returns:

JSONPath	Description
$	The root object/element or array.
@	The current object/element
. or []	The child operator.
..	Recursive descent. JSONPath borrows this syntax from E4X.
*	Wildcard. All objects/elements regardless of their names.
[]	Subscript operator. In JSON this is the native array operator.
[,]	JSONPath allows alternate names or array indices as a set.
[start:end:step]	Array slice operator borrowed from ES4.
?()	Applies a filter (script) expression.
()	Script expression, using the underlying script engine.